Simulation

Entry point for simulation

class qtealeaves.QuantumGreenTeaSimulation(model, operators, convergence, observables, folder_name_input='input', folder_name_output='output', file_name_input='TTN.in', tn_type=1, tensor_backend=1, mpo_mode=-1, disentangler=None, disentangler_file='disentangler.dat', has_log_file=False, store_checkpoints=True, verbosity=None, qgreentea_exe='./MainaTTN', py_tensor_backend=<qtealeaves.tensors.tensor_backend.TensorBackend object>)

Simulation class containing the model, the operators, the convergence settings, and the observables.

Arguments

modelinstance of RydbergModel

Defines the model, e.g., the Hamiltonian of the system.

operatorsinstance of TNOperators

Defines the operators used in the model and the observables.

convergenceinstance of TNConvergenceParameters

Specifies the convergence parameters for the simulation, for example the bond dimension.

observablesinstance of TNObservables

Defines the observables of the simulation. For details, check the corresponding class.

folder_name_inputstr, or callable; optional

Specifies the folder where the input is stored. Will be created if not existing. Path can contain subfolders. default to input

folder_name_outputstr, or callable; optional

Specifies the folder where the output is stored. Will be created if not existing. Path can contain subfolders. default to output

tn_typeint, optional

Specifies whether TTNs (1) or aTTNs (2) are used. The integer 0 is reserved for running ED simulations within in the python frontend. LPTN can be called via (3) and an MPS via LPTN as (4). The python backends can be used with non-symmetric TTNs (5), non-symmetric MPS (6), or non-symmetric TTOs (8). Additionally, for aTTN python backend choose (7), but only correlation measurement and no groundstate search is so far implemented. default to 1

tensor_backendint, optional

Choosing the underlying tensor, where the AbelianSymTensors are 1, and the Tensors are 2. default to 1

mpo_modeint, optional

Choosing the MPO representation inside the simulation, where the value -1 enables an auto-selection. The other values are TPO via iTPO (0), iTPO (1), iTPO with update (2, for quenches), iTPO with compression (3), and sparse MPO (10, partially enabled), indexed sparse MPO (11, partially enabled) Default to -1.

disentanglerNone or np.ndarray, optional

If the aTTN is used, the disentangler positions can be passed as a 2d numpy array with 2 rows and n columns, where n is the number of disentanglers. The indices must be passed as python indices starting from 0 in the mapped 1d system. The other option is to set it to None, in that case the disentangler positions are automatically selected if the tensor network is aTTN. Default to None.

disentangler_filestr, optional

If disentanglers are present, their positions are passed to fortran via this file. It will be located inside the input folder. default to disentangler.dat

has_log_filebool, optional

Flag if log file should be created instead of writing the output to standard out. If False, all output will go to standard out. Default to False (no log file)

store_checkpointsbool, optional

If True, the state will be written to a file after each sweep in the ground state search and after each time step in a time evolution. Ground state searches have the option to write checkpoints also after each tensor optimization, which the algorithm can decide on without control by the user. If True, delete_existing_folder must be False. Default to True

verbosityint, optional, deprecated

This parameter used to set the output verbosity of python functions. It is now ignored and deprecated in favor of logging.setLevel(). Default to 0.

qgreentea_exestr, optional

Set name of the executable to be used for calls to quantum green tea. Allows to customize beyond executables in the local folder. Default to ./MainaTTN

py_tensor_backendTensorBackend

Setup for tensor backend in python. Has to match simulation configuration when running with python, e.g., the integer tensor_backend. No meaning for fortrans simulations.

Reserved keywords of the simulation dictionary

The following keywords cannot be used for adapting simulations to the needs by the user, but have a predefined meaning. Additional predefined keywords may be imported, e.g., when using a specific model or a specific set of operators.

• continue_file : load file at the beginning of the simulation.

• use_mpo_from_continue_file : bool (Python only). Use MPO stored in continue file.

• seed : seed for random number generators.

• magic_numberfor debugging / developing to pass something to

  fortran.

• SymmetrySector

• SymmetryGenerators

• SymmetryTypes

• Quenches

• ed_sparse : bool, use in exact state emulator to switch between sparse and dense Hamiltonian.

• sweep_order : defines the sweep order for the statics (python only)

• exclude_from_hash : dictionary entries that will be excluded from hash.

Details

1. Checkpoints vs continue files: checkpointing is used to restart the same simulation. Continue files can be used to set the input state across simulations, but the simulation will start always at the beginning with this user-provided input state.

2. Hashing: hashes are generated to identify that a simulation setup did not change. For example, changes in a simulation which uses checkpoints can be detected this way.

autoselect_disentangler(params)

Given a number of sites and Hamiltonian, the function automatically chooses the positions for aTTN disentanglers. The function will try to place as many disentanglers as possible which do not violate the restrictions we have on the disentangler positions (for more info on the restrictions, look at the function check_disentangler_position).

Parameters

paramsdict

Dictionary with the simulation parameters.

Return

auto_disnp.array

Disentangler positions.

check_disentangler_position(params, disentangler_pos=None)

This function checks if the disentangler position input is valid.

Arguments

params: dict

Dictionary with the simulation parameters.

disentangler_posnp.array of shape [2, num_disentanglers], optional

An array containing the disentangler positions. Each column represents one disentangler. The first row indicates the position of the first site of the disentangler, and the second row indicates the position of the second site. If None, the disentangler positions are read from the self. Default to None.

static checkpoint_params_hash(params)

Generate hash of a simulation to identify if checkpointed simulation.

static combine_mpi_inputs(*args, mpi_input_file='mpi_exec_list.txt')

Combine different MPI inputs to one job list. Approaches for MPI and submit directory handling must match.

Arguments

mpi_input_filestr, optional

Allows to specify custom filename for job list. Existing files will be overwritten. Default to “mpi_exec_list.txt”

Returns

mpi_input_filestr or None

New file to run with MPI, None in the case of empty argument list.

extend_params(params)

Extend the parameters list and if the number of quantum trajectories is > 1, add to params the trajectory id and seed.

Arguments

paramsdict or list of dicts

The parameter dictionary or dictionaries, which is required to obtain the output folder.

get_dynamic_obs(params)

Return dictionaries with all observables of the static simulation, e.g., the dynamics. You obtain a nested list, the outer list is iterating over the quenches; the inner list over the time steps of each quench.

Arguments

paramsdict

The parameter dictionary, which is required to obtain the output folder.

get_full_fortran_nml(params)

Return the fortran nml filename serving as entry point for simulations.

get_groundstate_energy(params)

(DEPRECATED) Rudimentary way to extract the ground state energy via the convergence file.

Arguments

paramsdict

The parameter dictionary, which is required to obtain the output folder.

Details

Use get_static_obs in future.

get_static_obs(params)

Return a dictionary with all observables of the static simulation, e.g., the ground state search. For evolutions in temperature, i.e., LPTNs, a list of dictionaries is returned.

Arguments

paramsdict

The parameter dictionary, which is required to obtain the output folder.

run(params, delete_existing_folder=False, nthreads=1)

Run a simulation or multiple simulations possibly via threading.

Arguments

paramsdict or list of dicts

The parameter dictionary or dictionaries, which is required to obtain the output folder.

delete_existing_folderbool, optional

If flag is True, existing folder with potential results will be overwritten without warning. If False, an error is raised if the folders already exist. If True, store_checkpoints must be False. Default to False

nthreadsint, optional

If number of threads greater is one, we launch serial simulations. If greater than one, multiple threads are started to run simulations in parallel. Default to 1.

Details

We auto-select backends depending on the tn_type specified for the simulation.

• Exact diagonalization

• Python tensor network backend

• Fortran tensor network backend

If you run the threaded version, set the OMP_NUM_THREADS and MKL_NUM_THREADS (executable compiled with ifort) accordingly. The number of threads defined here times the OMP_NUM_THREADS should not exceed the number of your processors.

If running the TTN time evolution, workflow is the following:

#1 Loading the initial TTN state :

This can be either a random TTN, or the TTN read from a user-set file.

#2 Groundstate search to set the initial condition :

There are two options - initial condition is the groundstate of the specified Hamiltonian, or initial condition is a TTN from file set by a user. The groundstate is found by iterative search, therefore if the initial condition is set by user, put max_iter=0 in convergence parameters. Otherwise, set max_iter>0.

#3 Perform a time evolution starting from the obtained

initial condition.

run_single(params, delete_existing_folder=False)

Run simulation specified via the parameter dictionary.

Arguments

paramsdict

The parameter dictionary, which is required to obtain the output folder.

delete_existing_folderbool, optional

If flag is True, existing folder with potential results will be overwritten without warning. If False, an error is raised if the folders already exist. If True, store_checkpoints must be False. Default to False

Details

We auto-select backends depending on the tn_type specified for the simulation.

• Exact diagonalization

• Python tensor network backend

• Fortran tensor network backend

run_threaded(params, delete_existing_folder=False, nthreads=4)

Run simulation specified via the parameter dictionary.

Arguments

paramslist

List of the parameter dictionaries, which is required to obtain the output folder.

delete_existing_folderbool, optional

If flag is True, existing folder with potential results will be overwritten without warning. If False, an error is raised if the folders already exist. If True, store_checkpoints must be False. Default to False

nthreadsint, optional

Number of threads to start multiple simulations in parallel. Default to 4.

status(params)

Returns tuple of three integers containing the number of simulations not started, number of simulation started but not finished, and the number of finished simulations.

Arguments

paramsdict or list of dicts

The parameter dictionary or dictionaries, which is required to obtain the output folder.

write_disentangler(folder_name_input, params)

Write the disentangler file. Disentanglers are based on a 1D system or a system mapped to a 1d system. The two coordinates correspond to the two 1d positions.

Python indices go into the function, fortran indices will go out.

Arguments

folder_name_inputstr

Name of the input folders where the symmetry file should be written to.

paramsdict

Dictionary with the simulation parameters.

write_input(params, delete_existing_folder=False, do_return_params_ext=False)

Write input for a simulation or multiple simulations.

Arguments

paramsdict or list of dicts

The parameter dictionary or dictionaries, which is required to obtain the output folder.

delete_existing_folderbool, optional

If flag is True, existing folder with potential results will be overwritten without warning. If False, an error is raised if the folders already exist. If True, store_checkpoints must be False. Default to False

do_return_params_extbool, optional

Return additionally the full list of simulations, e.g., potentially extended with quantum trajectories. Default to False.

Returns

exec_listlist of strings

Commands to be executed to run the simulations written.

params_extlist of dicts

Only returned as second return value if do_return_params_ext=True. Contains the full list of simulation parameter dictionaries.

write_input_3(params)

Write all the input files for the input processor version 3. This version supports for example parameterization of models.

Arguments

paramsdict

Dictionary with the simulation parameters.

write_input_mpi(params, delete_existing_folder=False, submit_dir=None, use_rsync=False, mpi_input_file='mpi_exec_list.txt')

Write input for a multiple simulations with MPI. This function is targeted at HPC clusters and can also handling the copies of data between submit and scratch directories.

Arguments

paramsdict or list of dicts

The parameter dictionary or dictionaries, which is required to obtain the output folder.

delete_existing_folderbool, optional

If flag is True, existing folder with potential results will be overwritten without warning. If False, an error is raised if the folders already exist. If True, store_checkpoints must be False. Default to False

submit_dirstr or None, optional

If None, the path to the input and output folder is accessible from the current working directory. If a string is specified, the string will be used as a prefix to the input and output directory and they will be copied on runtime (by fortran) to the current working directory. Default to None

use_rsyncbool, optional

Set which command should be used for copy. By default, cp is used with use_rsync=False. If True, rsync will be used. The flag has only an effect if submit_dir is not None. Default to False.

mpi_input_filestr, optional

Allows to specify custom filename for job list. Existing files will be overwritten. Default to “mpi_exec_list.txt”

Returns

mpi_input_filestr

Input file to call the MPI executable with.

Details

The approach to run from a temporary scratch directory directly below the node is to specify the submit directory. The scratch directory is the working directory in this case and this way the input and output folder specified in the nml are still correct.

The other way round, i.e., the current working directory as submit directory, needs an update of the input and output folder specified in the nml file. This update is not possible if we access environment variables as $SCRATCH as fortran would have to do the string handling (while for the copying, the shell will substitute any environment variables automatically).

write_input_single(params, delete_existing_folder)

Write the input files for a simulation.

Arguments

paramsdict

The parameter dictionary, which is required to obtain the output folder.

delete_existing_folderbool

If flag is True, existing folder with potential results will be overwritten without warning. If False, an error is raised if the folders already exist. If True, store_checkpoints must be False.

static write_symmetries(folder_name_input, params)

Returns number of symmetries and input file.

Arguments

folder_name_inputstr

Name of the input folders where the symmetry file should be written to.

paramsdict

Dictionary with the simulation parameters.

class qtealeaves.ATTNSimulation(*args, **kwargs)

For backwards compatibility.

Tensor network simulation

class qtealeaves.simulation.tn_simulation.run_tn_simulation(simulation, params)

Run a full simulation with the python tensor network.

Arguments

simulationinstance of ATTNSimulation

Represents all the information on the simulation.

paramsdict

Dictionary containing the current parameters for the simulation.

class qtealeaves.simulation.tn_simulation.update_time_dependent_terms(state, time, params, params_ii, quench, mpo_mode, pos, force_rebuild_mpo=False)

Update the MPO layer according to the time-dependent couplings.

Arguments

state : _AbtractTN

timefloat

Time of the current step.

paramsdict

Used as initial starting point if params_ii is None

params_iidict

Parameters of the system in the last call.

quench :

Quench instance contains the time-dependent functions.

mpo_modeint

MPO mode required to decide on how to update the effective operators.

posint | tuple of ints

Default position of isometry center.

force_rebuild_mpobool, optional

Force method to re-calculate the MPO

Returns

state : state itself (updated inplace anyway)

params_iiupdated params dict (to check for time evolution

with constant checks)

class qtealeaves.simulation.tn_simulation.optimize(state, params, folder_name_output, store_checkpoints, sweep_order=None)

Optimize the tensor network by optimizing each tensor in the TN a number of times equal to num_sweeps. If not specified in sweep_order, the optimization is defined by state.default_sweep_order method. The number of sweeps and the other details are controlled in TNConvergenceParameters

Parameters

stateinstance of _AbstractTN

State to be optimized.

paramsdict

Contains parameters for simulation to resolve parameterization.

folder_name_inputstr

Folder path for output and storing checkpoints.

store_checkpointsbool

Flag if checkpoints should be stored (True) or not (False).

sweep_orderList[int] | List[Tuple[int]] | None, optional

PATH for the optimization, passed as the integer index of the tensor. Default to None.

Returns

_AbstractTN

State after optimization (in-place update not posisble for checkpoints).

np.ndarray[float], shape [n, 2]

Computational time and energy after each sweep

bool

Status if measurement is required (True) because the state was updated. In case of a loaded checkpoint which returns without additional optimizations, False is returned.

Exact state simulation

class qtealeaves.simulation.ed_simulation.run_ed_simulation(simulation, params)

Run a full simulation with the exact state vector.

Arguments

simulationinstance of ATTNSimulation

Represents all the information on the simulation.

paramsdict

Dictionary containing the current parameters for the simulation.

Quench for dynamics simulation

class qtealeaves.DynamicsQuench(dt_grid, time_evolution_mode=0, measurement_period=1, oqs_mode=0, check_superfluous=True)

Describing a quench of parameters for the dynamics part of a TN simulation. The parameters must be defined as a function taking the time and the simulation dictionary as arguments.

Arguments

dt_gridnumpy.ndarray, str, callable

Contains the list of time steps, which can differ. Moreover, it can be parameterized and be a callable or string.

time_evolution_modeint, optional

Defines the time evolution mode. 0 : automatic selector

(Defaults to 1 for tensor networks. For exact diagonalization, defaults to 10 for systems smaller than 10 sites and 11 for others.)

1 : one-tensor TDVP 2 : two-tensor TDVP 3 : two-tensor TDVP (2nd order) 4 : single-tensor TDVP (2nd order) 5 : 9 steps of one-site and one step of two-site TDVP 10 : exact diagonalization with full Hamiltonian matrix generated 11 : exact diagonalization with Krylov Not every network type might support all time evolution modes. Default to 0.

measurement_periodint, str, callable, optional

Allows to define a measurement period every n time steps. It considers only the time steps, not the time passed. There is always a measurement at the end of the quench. Default to 1.

oqs_modeint, optional

Controls the open quantum system evolution, where no open quantum is 0, quantum trajectories with jumps is 1, and quantum trajectories with norm only is 2. Default to 0.

check_superfluousbool, optional

If True, a warning is raised whenever a dictionary key is not in the required parameters. Default to True

Details

Open systems implement the Lindblad equation as

\[\frac{d}{dt} \rho = -i [H, \rho] + \sum \gamma (L \rho L^{\dagger} - \frac{1}{2} \{ L^{\dagger} L, \rho \})\]

eval_numeric_param(elem, params)

Evaluate a numeric parameter which might be defined via the parameter dictionary.

Arguments

elemcallable, string, or int/float

Defines the parameter either via a function which return the value, a string being an entry in the parameter dictionary, or directly as the numeric value.

paramsdict

The parameter dictionary, which will be passed to callables and used to evaluate string parameters.

get_dt_grid(params)

Evaluate the dt grid and return it.

Arguments

paramsdict

The parameter dictionary, which will be passed to callables and used to evaluate string parameters.

get_length(params)

Calculate the length of the time grid even for parameterized grids.

Arguments

paramsdict

The parameter dictionary, which will be passed to callables and used to evaluate string parameters.

iter_dts()

Generator yielding all the time steps dt within this quench. It returns the delta, not the current time in total.

iter_params(required_params, params, time_at_start=0.0)

Iterate over the all time steps and the required parameters within. Function returns the time-dependent parameters evaluated at mid-timestep. Moreover, we return the time-dependent parameters at the end of each time step to allow for measurements.

Arguments

required_paramsOrderedDict

Keys are the required parameters, values are the default values if no function is present.

paramsdict

Simulation parameter dictionary.

time_at_startfloat, optional

Time at the beginning of the quench, which allows to take into account previous quenches. Default to 0.0

iter_params_dts(params)

Iterate over parameters’s time steps. Coupling with a time-step dt greater than zero, are intended for the time evolution. Every second parameter is 0 or -99 and indicating the values are at the end point for the measurements, i.e., doing measurements (zero) or doing no measurement (-99), respectively. Up to now, no other values less or equal to zero are associated with some special meaning.

Arguments

paramsdict

Simulation parameter dictionary.

Logging

Logging is handled through python’s logging module, giving the user plenty of room for customization on where (file, console, etc.), how (text formatting), and what to log - see e.g. Examples/Logging_setup.py. Filtering is mostly based on the severity level of the log record and on its source (from which module it was emitted).

If no custom logging setup is provided, qtealeaves will set some defaults: logging to the console or to a sim.log file in the simulation output folder, depending on the argument has_log_file passed at simulation initialization. By default, logs with level “WARNING” or higher will be emitted, except for simulation-wide log records coming from the qtealeaves.simulation sub-package, for which “INFO” or higher is logged. When logging to a file we also call logging.captureWarnings() to enable capturing messages emitted via warnings.warn().

When customizing logging, you have to explicitly set the level of the simulation-wide logger via get_logger(“qtealeaves.simulation”).setLevel(LEVEL) if you want something different from “INFO”. You may also want to enable capturing warnings, regardless of the value passed for has_log_file.